Real-World Examples

Let's look at some real-world examples of how properties are used in web development and other contexts. Create a file named real_world_examples.py with the following code:

# File: properties/real_world_examples.py

import re
import json
from datetime import datetime, timedelta
import os


class Config:
    """A configuration class with lazy loading and type validation"""
    
    def __init__(self, config_file=None):
        self._config_file = config_file
        self._data = {}
        self._loaded = False
    
    def _load_if_needed(self):
        """Lazy load the config file"""
        if not self._loaded and self._config_file and os.path.exists(self._config_file):
            with open(self._config_file, 'r') as f:
                self._data = json.load(f)
            self._loaded = True
    
    @property
    def database_url(self):
        """Get the database URL"""
        self._load_if_needed()
        return self._data.get('database_url', 'sqlite:///default.db')
    
    @database_url.setter
    def database_url(self, value):
        if not isinstance(value, str):
            raise TypeError("Database URL must be a string")
        self._data['database_url'] = value
    
    @property
    def debug_mode(self):
        """Get the debug mode setting"""
        self._load_if_needed()
        return self._data.get('debug_mode', False)
    
    @debug_mode.setter
    def debug_mode(self, value):
        if not isinstance(value, bool):
            raise TypeError("Debug mode must be a boolean")
        self._data['debug_mode'] = value
    
    @property
    def api_keys(self):
        """Get API keys (dictionary)"""
        self._load_if_needed()
        return self._data.get('api_keys', {}).copy()  # Return a copy to prevent modification
    
    @api_keys.setter
    def api_keys(self, value):
        if not isinstance(value, dict):
            raise TypeError("API keys must be a dictionary")
        self._data['api_keys'] = value
    
    def save(self):
        """Save the configuration to the file"""
        if not self._config_file:
            raise ValueError("No config file specified")
        
        with open(self._config_file, 'w') as f:
            json.dump(self._data, f, indent=2)
        
        self._loaded = True


class URLBuilder:
    """A class for building URLs with proper encoding and validation"""
    
    def __init__(self, base_url):
        # Validate and store the base URL
        if not isinstance(base_url, str):
            raise TypeError("Base URL must be a string")
        
        # Ensure the base URL is properly formatted
        if not base_url.startswith(('http://', 'https://')):
            raise ValueError("Base URL must start with http:// or https://")
        
        # Remove trailing slash for consistency
        self._base_url = base_url.rstrip('/')
        
        # Initialize components
        self._path = ''
        self._query_params = {}
        self._fragment = ''
    
    @property
    def base_url(self):
        """The base URL (scheme + domain)"""
        return self._base_url
    
    @property
    def path(self):
        """The URL path"""
        return self._path
    
    @path.setter
    def path(self, value):
        if not isinstance(value, str):
            raise TypeError("Path must be a string")
        
        # Ensure the path starts with a slash but doesn't end with one
        self._path = '/' + value.strip('/') if value else ''
    
    @property
    def query_params(self):
        """The query parameters as a dictionary"""
        return self._query_params.copy()  # Return a copy to prevent modification
    
    def add_query_param(self, key, value):
        """Add a query parameter"""
        self._query_params[key] = value
    
    def clear_query_params(self):
        """Clear all query parameters"""
        self._query_params.clear()
    
    @property
    def fragment(self):
        """The URL fragment (the part after #)"""
        return self._fragment
    
    @fragment.setter
    def fragment(self, value):
        if not isinstance(value, str):
            raise TypeError("Fragment must be a string")
        
        # Remove the leading # if present
        self._fragment = value.lstrip('#')
    
    @property
    def url(self):
        """
        The complete URL formed by joining all components
        This is a calculated property based on all the components
        """
        url = self._base_url + self._path
        
        # Add query parameters if any
        if self._query_params:
            # Simple URL encoding for demonstration purposes
            # In a real implementation, use urllib.parse
            params = '&'.join(f'{k}={v}' for k, v in self._query_params.items())
            url += '?' + params
        
        # Add fragment if any
        if self._fragment:
            url += '#' + self._fragment
        
        return url


class CachedProperty:
    """A descriptor that caches the result of a property"""
    
    def __init__(self, func):
        self.func = func
        self.__doc__ = func.__doc__
    
    def __get__(self, instance, owner):
        if instance is None:
            return self
        
        # Calculate the value
        value = self.func(instance)
        
        # Cache the value on the instance
        setattr(instance, self.func.__name__, value)
        
        return value


class WebPageAnalyzer:
    """A class that analyzes web page content with cached properties"""
    
    def __init__(self, html_content):
        self.html_content = html_content
    
    @CachedProperty
    def word_count(self):
        """Count the number of words in the HTML content"""
        # This is a simplified example - in real life we would parse the HTML properly
        # and extract just the text content
        print("Calculating word count...")
        words = re.findall(r'\b\w+\b', self.html_content)
        return len(words)
    
    @CachedProperty
    def link_count(self):
        """Count the number of links in the HTML content"""
        print("Counting links...")
        links = re.findall(r']*href=[\'"]([^\'"]+)[\'"]', self.html_content)
        return len(links)
    
    @CachedProperty
    def image_count(self):
        """Count the number of images in the HTML content"""
        print("Counting images...")
        images = re.findall(r']*src=[\'"]([^\'"]+)[\'"]', self.html_content)
        return len(images)
    
    @property
    def stats(self):
        """Get a dictionary of all statistics"""
        return {
            'word_count': self.word_count,
            'link_count': self.link_count,
            'image_count': self.image_count
        }


class JWTToken:
    """A class for working with JWT tokens"""
    
    def __init__(self, token=None):
        self._token = token
        self._payload = None
        self._header = None
        self._signature = None
        self._expiry = None
        
        # If a token was provided, decode it
        if token:
            self._decode_token()
    
    def _decode_token(self):
        """Decode the token into its parts"""
        # This is a simplified implementation for demonstration
        # In a real implementation, use a JWT library
        
        try:
            parts = self._token.split('.')
            if len(parts) != 3:
                raise ValueError("Invalid JWT token format")
            
            # In a real implementation, these would be base64 decoded and parsed
            self._header = {"alg": "HS256", "typ": "JWT"}
            self._payload = {"sub": "1234567890", "name": "John Doe", "exp": int((datetime.now() + timedelta(hours=1)).timestamp())}
            self._signature = "signature"
            
            # Extract expiry time if present
            if "exp" in self._payload:
                self._expiry = datetime.fromtimestamp(self._payload["exp"])
        
        except Exception as e:
            raise ValueError(f"Failed to decode token: {e}")
    
    @property
    def token(self):
        """The JWT token string"""
        return self._token
    
    @token.setter
    def token(self, value):
        if not isinstance(value, str):
            raise TypeError("Token must be a string")
        
        self._token = value
        self._decode_token()
    
    @property
    def payload(self):
        """The token payload (claims)"""
        return self._payload.copy() if self._payload else None
    
    @property
    def header(self):
        """The token header"""
        return self._header.copy() if self._header else None
    
    @property
    def subject(self):
        """The subject claim from the payload"""
        return self._payload.get("sub") if self._payload else None
    
    @property
    def expiry(self):
        """The expiry time of the token"""
        return self._expiry
    
    @property
    def is_expired(self):
        """Check if the token is expired"""
        if not self._expiry:
            return False
        return datetime.now() > self._expiry
    
    @property
    def time_to_expiry(self):
        """Time remaining until the token expires"""
        if not self._expiry:
            return None
        
        if self.is_expired:
            return timedelta(0)
        
        return self._expiry - datetime.now()


# Demo real-world examples
if __name__ == "__main__":
    # Config example
    print("Config example:")
    # Uncomment to test with a real file
    # config = Config("config.json")
    config = Config()  # In-memory only for demo
    
    print(f"Default database URL: {config.database_url}")
    print(f"Default debug mode: {config.debug_mode}")
    
    config.database_url = "postgresql://user:pass@localhost/mydb"
    config.debug_mode = True
    config.api_keys = {"google": "abc123", "twitter": "xyz789"}
    
    print(f"Updated database URL: {config.database_url}")
    print(f"Updated debug mode: {config.debug_mode}")
    print(f"API keys: {config.api_keys}")
    
    # Uncommment to save to file
    # config.save()
    
    # URLBuilder example
    print("\nURLBuilder example:")
    builder = URLBuilder("https://api.example.com")
    
    builder.path = "/users/profile"
    builder.add_query_param("user_id", "12345")
    builder.add_query_param("format", "json")
    builder.fragment = "personal-info"
    
    print(f"Built URL: {builder.url}")
    
    builder.path = "/search"
    builder.clear_query_params()
    builder.add_query_param("q", "python properties")
    builder.fragment = ""
    
    print(f"New URL: {builder.url}")
    
    # WebPageAnalyzer example
    print("\nWebPageAnalyzer example:")
    html = """
    
    
    
    
        
Hello, World!
        
This is a test page with some text.
        Link 1
        Link 2
        
        
        
    
    
    """
    
    analyzer = WebPageAnalyzer(html)
    
    # First access calculates the value
    print(f"Word count: {analyzer.word_count}")
    
    # Second access uses the cached value
    print(f"Word count (cached): {analyzer.word_count}")
    
    # Access other properties
    print(f"Link count: {analyzer.link_count}")
    print(f"Image count: {analyzer.image_count}")
    
    # Get all stats
    print(f"All stats: {analyzer.stats}")
    
    # JWTToken example
    print("\nJWTToken example:")
    # In a real implementation, this would be a valid JWT token
    jwt = JWTToken("header.payload.signature")
    
    print(f"Token: {jwt.token}")
    print(f"Header: {jwt.header}")
    print(f"Payload: {jwt.payload}")
    print(f"Subject: {jwt.subject}")
    print(f"Expiry: {jwt.expiry}")
    print(f"Is expired: {jwt.is_expired}")
    print(f"Time to expiry: {jwt.time_to_expiry}")

Code Breakdown:

• Config class:
  • Uses properties for lazy loading configuration from a file
  • Type validation for configuration values
  • Default values for missing configuration
  • Defensive copying for mutable values (api_keys)
• URLBuilder class:
  • Uses properties to build and validate URL components
  • Computed url property that combines all components
  • Type and format validation
• CachedProperty class:
  • A property descriptor that caches the result of expensive calculations
  • Used in WebPageAnalyzer to avoid recalculating values
• WebPageAnalyzer class:
  • Uses the CachedProperty descriptor for expensive calculations
  • Regular property (stats) that combines other properties
• JWTToken class:
  • Properties for accessing JWT token components
  • Computed properties for token state (is_expired, time_to_expiry)
  • Token parsing and validation

Key Patterns in Real-World Use:

1. Lazy Loading: Properties can delay expensive operations until data is actually needed.
2. Caching: Properties can cache results to improve performance for expensive calculations.
3. Computed Aggregates: Properties can combine multiple values into useful aggregates.
4. Domain-Specific Validation: Properties can enforce domain rules specific to the application.
5. Immutable Views: Properties can provide read-only views or defensive copies of internal data.
6. Custom Descriptors: For advanced cases, custom descriptors like CachedProperty extend the property pattern.

Real-world analogy: These examples are like various smart home devices working together. The Config class is like a smart home hub that loads settings only when needed. The URLBuilder is like a smart navigation system that ensures all directions are valid. The CachedProperty is like a smart thermostat that remembers the last temperature reading to avoid constantly checking. The JWTToken is like a smart lock that handles all the security details while providing a simple interface.