"""
This module demonstrates a generic function with in-line comments
for Sphinx auto documentation.
This module contains utility functions and classes to showcase
how Sphinx autodoc can extract and format Python documentation.
Classes:
ExampleClass: A simple example class with methods.
Functions:
main(): Performs an example operation.
calculate_sum(a, b): Returns the sum of two numbers.
process_data(data): Processes a list of data items.
Examples:
Basic usage of the module::
from src import amodule
# Call the main function
amodule.main()
# Use the calculator
result = amodule.calculate_sum(5, 3)
print(f"Result: {result}")
"""
import unittest
from typing import List, Optional, Union
[docs]
class ExampleClass:
"""
An example class to demonstrate Sphinx documentation for classes.
This class provides basic functionality for demonstration purposes.
Attributes:
name (str): The name of the instance.
value (int): A numeric value associated with the instance.
Args:
name (str): The name to assign to this instance.
value (int, optional): Initial value. Defaults to 0.
Examples:
Creating and using an ExampleClass instance::
>>> obj = ExampleClass("test", 42)
>>> obj.get_info()
'Name: test, Value: 42'
"""
[docs]
def __init__(self, name: str, value: int = 0):
"""Initialize the ExampleClass instance."""
self.name = name
self.value = value
[docs]
def get_info(self) -> str:
"""
Get formatted information about this instance.
Returns:
str: A formatted string containing the name and value.
"""
return f"Name: {self.name}, Value: {self.value}"
[docs]
def update_value(self, new_value: int) -> None:
"""
Update the value attribute.
Args:
new_value (int): The new value to set.
Raises:
TypeError: If new_value is not an integer.
"""
if not isinstance(new_value, int):
raise TypeError("Value must be an integer")
self.value = new_value
[docs]
def main() -> None:
"""
Main function to run the program.
This function demonstrates basic functionality and serves as
an entry point for the module. It creates an example instance
and performs some operations.
Returns:
None
Examples:
>>> main() # doctest: +SKIP
"""
print("Starting uv-components example...")
# Create an example instance
example = ExampleClass("demo", 10)
print(example.get_info())
# Demonstrate calculation
result = calculate_sum(5, 3)
print(f"Calculation result: {result}")
# Process some sample data
sample_data = [1, 2, 3, 4, 5]
processed = process_data(sample_data)
print(f"Processed data: {processed}")
[docs]
def calculate_sum(a: Union[int, float], b: Union[int, float]) -> Union[int, float]:
"""
Calculate the sum of two numbers.
This function adds two numeric values together and returns the result.
It supports both integers and floating-point numbers.
Args:
a (Union[int, float]): The first number to add.
b (Union[int, float]): The second number to add.
Returns:
Union[int, float]: The sum of a and b.
Examples:
>>> calculate_sum(2, 3)
5
>>> calculate_sum(2.5, 1.5)
4.0
>>> calculate_sum(-1, 1)
0
"""
return a + b
[docs]
def process_data(data: List[Union[int, float]]) -> Optional[List[Union[int, float]]]:
"""
Process a list of numeric data.
This function takes a list of numbers and performs basic processing:
- Filters out negative numbers
- Multiplies each remaining number by 2
Args:
data (List[Union[int, float]]): A list of numeric values to process.
Returns:
Optional[List[Union[int, float]]]: Processed list of numbers, or None if input is empty.
Raises:
TypeError: If data is not a list or contains non-numeric values.
Examples:
>>> process_data([1, 2, 3])
[2, 4, 6]
>>> process_data([1, -2, 3, -4, 5])
[2, 6, 10]
>>> process_data([])
"""
if not isinstance(data, list):
raise TypeError("Input must be a list")
if not data:
return None
# Validate all items are numeric
for item in data:
if not isinstance(item, (int, float)):
raise TypeError("All items in the list must be numeric")
# Filter out negative numbers and multiply by 2
processed = [item * 2 for item in data if item >= 0]
return processed if processed else None