115 lines
3.0 KiB
Python
115 lines
3.0 KiB
Python
"""Example Python module for Doc2Man demonstration.
|
|
|
|
This module contains various function types to demonstrate
|
|
the docstring parsing capabilities of Doc2Man.
|
|
"""
|
|
|
|
|
|
def greet(name: str, greeting: str = "Hello") -> str:
|
|
"""Greet a person with a custom greeting message.
|
|
|
|
Args:
|
|
name: The name of the person to greet. Should be a non-empty string.
|
|
greeting: The greeting word to use. Defaults to "Hello".
|
|
|
|
Returns:
|
|
A formatted greeting string like "Hello, John!".
|
|
|
|
Raises:
|
|
ValueError: If name is empty or None.
|
|
|
|
Examples:
|
|
>>> greet("Alice")
|
|
'Hello, Alice!'
|
|
>>> greet("Bob", "Hi")
|
|
'Hi, Bob!'
|
|
"""
|
|
if not name:
|
|
raise ValueError("Name cannot be empty")
|
|
return f"{greeting}, {name}!"
|
|
|
|
|
|
def calculate_sum(numbers: list[float]) -> dict[str, float]:
|
|
"""Calculate the sum and average of a list of numbers.
|
|
|
|
Args:
|
|
numbers: A list of numeric values. Must not be empty.
|
|
|
|
Returns:
|
|
A dictionary containing:
|
|
- sum: The total sum of all numbers
|
|
- average: The arithmetic mean
|
|
- count: The number of elements
|
|
|
|
Raises:
|
|
ValueError: If the input list is empty.
|
|
|
|
Examples:
|
|
>>> calculate_sum([1, 2, 3, 4, 5])
|
|
{'sum': 15, 'average': 3.0, 'count': 5}
|
|
"""
|
|
if not numbers:
|
|
raise ValueError("Input list cannot be empty")
|
|
|
|
total = sum(numbers)
|
|
count = len(numbers)
|
|
|
|
return {
|
|
"sum": total,
|
|
"average": total / count if count > 0 else 0,
|
|
"count": count
|
|
}
|
|
|
|
|
|
class FileHandler:
|
|
"""A class for handling file operations.
|
|
|
|
This class provides methods for reading, writing,
|
|
and processing files with proper error handling.
|
|
|
|
Attributes:
|
|
filepath: The path to the file being handled.
|
|
"""
|
|
|
|
def __init__(self, filepath: str):
|
|
"""Initialize the FileHandler with a file path.
|
|
|
|
Args:
|
|
filepath: Path to the file to handle.
|
|
"""
|
|
self.filepath = filepath
|
|
|
|
def read(self, encoding: str = "utf-8") -> str:
|
|
"""Read the entire content of the file.
|
|
|
|
Args:
|
|
encoding: The text encoding to use. Defaults to UTF-8.
|
|
|
|
Returns:
|
|
The file contents as a string.
|
|
|
|
Raises:
|
|
FileNotFoundError: If the file doesn't exist.
|
|
UnicodeDecodeError: If the file cannot be decoded.
|
|
|
|
Examples:
|
|
>>> handler = FileHandler("example.txt")
|
|
>>> content = handler.read()
|
|
"""
|
|
with open(self.filepath, "r", encoding=encoding) as f:
|
|
return f.read()
|
|
|
|
def write(self, content: str, encoding: str = "utf-8") -> None:
|
|
"""Write content to the file.
|
|
|
|
Args:
|
|
content: The text content to write.
|
|
encoding: The text encoding to use. Defaults to UTF-8.
|
|
|
|
Examples:
|
|
>>> handler = FileHandler("output.txt")
|
|
>>> handler.write("Hello, World!")
|
|
"""
|
|
with open(self.filepath, "w", encoding=encoding) as f:
|
|
f.write(content)
|