SiaPy Style Guide

Enforce consistent code style and conventions when working on the SiaPy spectral image processing library.

Type Hints & Python Version

Code Style

Class Design

Method Naming Conventions

Follow these strict naming patterns:

| Pattern | Use Case | Examples |

|---------|----------|----------|

| Simple noun | Properties (read-only access) | `name`, `value`, `size` |

| `get_*` | Expensive getters (computation/I/O) | `get_statistics()`, `get_metadata()` |

| `from_*` | Constructor/factory methods | `from_point()`, `from_dict()`, `from_file()` |

| `to_*` | Data converters/transformers | `to_numpy()`, `to_pandas()`, `to_dict()` |

| `open_*` | File loaders | `open_shapefile()`, `open_image()` |

| `save_*` | File savers | `save_to_csv()`, `save_image()` |

| Action verbs | Operations/actions | `calculate()`, `process()`, `transform()` |

| Plural nouns | Batch operations | `process_items()`, `load_images()` |

| `is_*`, `has_*`, `can_*` | Boolean queries | `is_valid()`, `has_data()`, `can_process()` |

| `create_*` | Factory methods | `create_instance()`, `create_from_config()` |

Class Organization

Order class members consistently:

1. **Dunder methods** (`__init__`, `__repr__`, etc.)

2. **Class methods** (`@classmethod`)

3. **Properties** (`@property`)

4. **Instance methods**

Error Handling

**Always use custom exceptions from `siapy.core.exceptions`**:

```python

from siapy.core.exceptions import (

InvalidFilepathError,

InvalidInputError,

InvalidTypeError,

ProcessingError,

ConfigurationError,

MethodNotImplementedError,

DirectInitializationError

)

```

Logging

**Always use the SiaPy logger**:

```python

from siapy.core import logger

logger.info("Processing started")

logger.warning("Invalid value detected")

logger.error("Failed to load file", exc_info=True)

```

Interfaces & Abstract Classes

Examples

```python

from dataclasses import dataclass

from typing import Protocol

from siapy.core import logger

from siapy.core.exceptions import InvalidInputError

Data class example

@dataclass

class SpectralImage:

data: np.ndarray

wavelengths: list[float]

@property

def shape(self) -> tuple[int, ...]:

return self.data.shape

def get_statistics(self) -> dict[str, float]:

"""Expensive computation"""

logger.info("Computing statistics")

return {"mean": self.data.mean(), "std": self.data.std()}

@classmethod

def from_file(cls, path: str) -> "SpectralImage":

if not path.endswith(".hdr"):

raise InvalidInputError(f"Invalid file type: {path}")

# load and return

def to_numpy(self) -> np.ndarray:

return self.data.copy()

Protocol example

class Processor(Protocol):

def process(self, data: np.ndarray) -> np.ndarray: ...

def is_valid(self) -> bool: ...

```