API Reference

This page demonstrates how to document APIs using Sphinx.

Module Overview

This module provides examples of how to document Python APIs.

Classes

class example_module.ExampleClass(name, value=None)

A sample class for demonstration.

Parameters:

  • name (str) – The name of the instance

  • value (int or None) – Optional initial value

name

The name of the instance (read-only)

Type:

str

value

The current value

Type:

int

get_info()

Get information about the instance.

Returns:

A dictionary containing name and value

Return type:

dict

Example:

>>> obj = ExampleClass("test", 42)
>>> obj.get_info()
{'name': 'test', 'value': 42}
update_value(new_value)

Update the instance value.

Parameters:

new_value (int) – The new value to set

Raises:

ValueError – If new_value is negative

Returns:

The previous value

Return type:

int

Functions

example_module.calculate_sum(a, b)

Calculate the sum of two numbers.

Parameters:

  • a (float) – First number

  • b (float) – Second number

Returns:

The sum of a and b

Return type:

float

Example:

>>> calculate_sum(2.5, 3.7)
6.2
example_module.process_data(data, callback=None, **kwargs)

Process data with optional callback.

Parameters:

  • data (list) – List of items to process

  • callback (callable) – Optional callback function

  • kwargs – Additional keyword arguments

Returns:

Processed data

Return type:

list

Raises:

TypeError – If data is not a list

Constants

example_module.VERSION

Current API version

Type:

str

Value:

“1.0.0”

example_module.MAX_RETRIES

Maximum number of retry attempts

Type:

int

Value:

3

Exceptions

exception example_module.CustomError

Base exception for all custom errors.

exception example_module.ValidationError

Raised when validation fails.

field

The field that failed validation

message

Error message

Code Examples

Basic Usage

from example_module import ExampleClass, calculate_sum

# Create an instance
obj = ExampleClass("demo", 100)

# Use the calculate_sum function
result = calculate_sum(10, 20)
print(f"Sum: {result}")

# Update value
old_value = obj.update_value(200)
print(f"Updated from {old_value} to {obj.value}")

Error Handling

from example_module import ValidationError

try:
    # Some validation code
    validate_input(user_data)
except ValidationError as e:
    print(f"Validation failed for {e.field}: {e.message}")

See Also