Legacy-code integrity tamper

import json
from datetime import datetime

def process_data(data):
    result = []
    for item in data:
        if item.get('value', 0) > 0:
            result.append({
                'id': item.get('id'),
                'processed': True,
                'timestamp': datetime.now().isoformat()
            })
    return result

def calculate_avg(nums):
    total = 0
    count = len(nums)
    for n in nums:
        total += n
    return total / count if count > 0 else 0

def filter_users(users, min_age=18):
    filtered = []
    for user in users:
        if user.get('age', 0) >= min_age:
            filtered.append(user)
    return filtered

def save_to_file(data, filename):
    with open(filename, 'w') as f:
        json.dump(data, f)
    return True

class DataStore:
    def __init__(self):
        self._data = {}

    def add(self, key, value):
        self._data[key] = value

    def get(self, key):
        return self._data.get(key)

    def remove(self, key):
        if key in self._data:
            del self._data[key]

def format_output(items):
    output = []
    for i, item in enumerate(items):
        output.append(f"{i+1}. {item}")
    return "\n".join(output)

"""
Legacy code module with comprehensive documentation.

This module provides utility functions for data processing, filtering,
and storage operations. It includes functions for processing data records,
calculating averages, filtering users by age, file operations, and a
simple DataStore class for key-value storage.
"""

import json
from datetime import datetime


def process_data(data):
    """
    Process a list of data items and filter for positive values.

    This function iterates through a list of dictionaries, filters out
    items that have a 'value' key with a positive number (> 0), and
    returns a new list with processed information including a timestamp.

    Args:
        data (list): A list of dictionaries, each containing at least
                     an 'id' key. Optional 'value' key for filtering.

    Returns:
        list: A list of dictionaries containing the 'id', 'processed'
              (set to True), and 'timestamp' (ISO format) for each item
              where value > 0. Returns an empty list if no items match.

    Example:
        >>> data = [{'id': 1, 'value': 10}, {'id': 2, 'value': -5}]
        >>> result = process_data(data)
        >>> len(result)
        1
    """
    # Initialize an empty list to store processed items
    result = []

    # Iterate through each item in the input data
    for item in data:
        # Check if the item has a 'value' key and if it's greater than 0
        # Default to 0 if 'value' key is missing (treats missing as invalid)
        if item.get('value', 0) > 0:
            # Append a new dictionary with processed information
            result.append({
                'id': item.get('id'),  # Preserve the original ID
                'processed': True,      # Mark as successfully processed
                # Add current timestamp in ISO 8601 format for tracking
                'timestamp': datetime.now().isoformat()
            })

    # Return the list of processed items (may be empty)
    return result


def calculate_avg(nums):
    """
    Calculate the arithmetic mean of a list of numbers.

    This function computes the average by summing all numbers and dividing
    by the count. It handles edge cases like empty lists gracefully.

    Args:
        nums (list): A list of numeric values (integers or floats).

    Returns:
        float: The arithmetic mean of all numbers in the list.
               Returns 0 if the list is empty to avoid division by zero.

    Example:
        >>> calculate_avg([10, 20, 30])
        20.0
        >>> calculate_avg([])
        0
    """
    # Initialize total to 0 for summing
    total = 0

    # Get the count of numbers to handle empty list case
    count = len(nums)

    # Iterate through each number and add to total
    for n in nums:
        total += n

    # Return average only if count > 0, otherwise return 0 to avoid ZeroDivisionError
    return total / count if count > 0 else 0


def filter_users(users, min_age=18):
    """
    Filter a list of users based on a minimum age requirement.

    This function filters user dictionaries to include only those
    where the age is greater than or equal to the specified minimum.
    Users without an age field are excluded by default.

    Args:
        users (list): A list of dictionaries representing users,
                      each containing an 'age' key.
        min_age (int, optional): The minimum age threshold for inclusion.
                                 Defaults to 18.

    Returns:
        list: A list of user dictionaries that meet the age requirement.
              Returns an empty list if no users match.

    Example:
        >>> users = [{'name': 'Alice', 'age': 25}, {'name': 'Bob', 'age': 16}]
        >>> filter_users(users, 18)
        [{'name': 'Alice', 'age': 25}]
    """
    # Initialize empty list to store filtered users
    filtered = []

    # Iterate through each user in the input list
    for user in users:
        # Get user age, defaulting to 0 if not present
        # This ensures users without age are filtered out
        if user.get('age', 0) >= min_age:
            # Add user to filtered list if they meet the age requirement
            filtered.append(user)

    # Return the filtered list of users
    return filtered


def save_to_file(data, filename):
    """
    Save data to a JSON file.

    This function serializes the provided data structure to JSON
    and writes it to the specified file. The file is created or
    overwritten if it already exists.

    Args:
        data (dict or list): The data structure to serialize to JSON.
                             Must be JSON-serializable (dict, list, etc.).
        filename (str): The path and name of the file to write to.

    Returns:
        bool: Always returns True to indicate successful write operation.

    Example:
        >>> data = {'name': 'Test', 'values': [1, 2, 3]}
        >>> save_to_file(data, 'output.json')
        True
    """
    # Open file in write mode (creates if not exists, overwrites if exists)
    with open(filename, 'w') as f:
        # Serialize data to JSON and write to file
        # indent=2 could be added for pretty-printing if needed
        json.dump(data, f)

    # Return True to indicate successful completion
    return True


class DataStore:
    """
    A simple in-memory key-value data store.

    This class provides basic CRUD (Create, Read, Delete) operations
    for storing and retrieving data in memory. Data is not persisted
    and will be lost when the program exits.

    Attributes:
        _data (dict): Internal dictionary storing key-value pairs.

    Example:
        >>> store = DataStore()
        >>> store.add('name', 'John')
        >>> store.get('name')
        'John'
        >>> store.remove('name')
    """

    def __init__(self):
        """
        Initialize a new DataStore instance.

        Creates an empty internal dictionary to store key-value pairs.
        No external parameters required.
        """
        # Initialize empty dictionary for internal storage
        self._data = {}

    def add(self, key, value):
        """
        Add or update a key-value pair in the data store.

        Args:
            key (str): The key to associate with the value.
            value (any): The value to store. Can be any Python object.

        Returns:
            None: This method does not return anything.

        Example:
            >>> store = DataStore()
            >>> store.add('user', {'name': 'Alice', 'age': 30})
        """
        # Store the value using the key (overwrites if key already exists)
        self._data[key] = value

    def get(self, key):
        """
        Retrieve a value by its key from the data store.

        Args:
            key (str): The key to look up in the store.

        Returns:
            The value associated with the key if found, otherwise None.

        Example:
            >>> store = DataStore()
            >>> store.add('name', 'Bob')
            >>> store.get('name')
            'Bob'
            >>> store.get('missing')  # Returns None
        """
        # Use .get() to safely retrieve, returns None if key not found
        return self._data.get(key)

    def remove(self, key):
        """
        Remove a key-value pair from the data store.

        Removes the specified key and its associated value from the
        internal dictionary. Does nothing if the key doesn't exist.

        Args:
            key (str): The key to remove from the store.

        Returns:
            None: This method does not return anything.

        Example:
            >>> store = DataStore()
            >>> store.add('temp', 'value')
            >>> store.remove('temp')  # Key removed
        """
        # Check if key exists before attempting deletion
        # This prevents KeyError if key is not present
        if key in self._data:
            # Delete the key-value pair from internal dictionary
            del self._data[key]


def format_output(items):
    """
    Format a list of items as a numbered text output.

    This function takes a list of items and returns a string where
    each item is on its own line, prefixed with its position number
    (starting from 1).

    Args:
        items (list): A list of items to format. Items are converted
                      to strings using the f-string formatting.

    Returns:
        str: A single string with each item on a new line, prefixed
             with its 1-based index and a period.

    Example:
        >>> items = ['apple', 'banana', 'cherry']
        >>> print(format_output(items))
        1. apple
        2. banana
        3. cherry
    """
    # Initialize empty list to store formatted lines
    output = []

    # Iterate through items with their index (0-based enumeration)
    # Using enumerate to get both index and item for numbering
    for i, item in enumerate(items):
        # Format each item as "{number}. {item}"
        # i+1 converts 0-based index to 1-based numbering
        output.append(f"{i+1}. {item}")

    # Join all formatted lines with newline characters
    # Returns a single string with all items
    return "\n".join(output)