FiftyOne Code Style

Module Template

"""
Module description.

| Copyright 2017-2025, Voxel51, Inc.
| `voxel51.com <https://voxel51.com/>`_
|
"""
# Standard library
import logging
import os

# Third-party
import numpy as np

# eta (Voxel51 utilities)
import eta.core.utils as etau

# FiftyOne
import fiftyone.core.fields as fof
import fiftyone.core.labels as fol
import fiftyone.core.utils as fou

logger = logging.getLogger(__name__)


def public_function(arg):
    """Public API function."""
    return _helper(arg)


def _helper(arg):
    """Private helper (underscore prefix)."""
    return arg

Import Organization

Four groups, alphabetized within each:

| Group | Example | |-------|---------| | 1. Standard library | import logging, import os | | 2. Third-party | import numpy as np, from PIL import Image | | 3. eta packages | import eta.core.utils as etau | | 4. FiftyOne | import fiftyone.core.labels as fol |

FiftyOne Import Aliases

| Module | Alias | |--------|-------| | fiftyone | fo | | fiftyone.core.labels | fol | | fiftyone.core.fields | fof | | fiftyone.core.media | fom | | fiftyone.core.storage | fos | | fiftyone.core.utils | fou | | fiftyone.utils.image | foui | | fiftyone.utils.video | fouv |

Docstrings (Google-Style)

Function Docstring

def get_operator(operator_uri, enabled=True):
    """Gets the operator with the given URI.

    Args:
        operator_uri: the operator URI
        enabled (True): whether to include only enabled operators (True) or
            only disabled operators (False) or all operators ("all")

    Returns:
        an :class:`fiftyone.operators.Operator`

    Raises:
        ValueError: if the operator is not found
    """

Class Docstring

class ImageMetadata(Metadata):
    """Class for storing metadata about image samples.

    Args:
        size_bytes (None): the size of the image on disk, in bytes
        mime_type (None): the MIME type of the image
        width (None): the width of the image, in pixels
        height (None): the height of the image, in pixels
    """

Key patterns:

Args with defaults: param (default): description
Multi-line descriptions: indent continuation
Cross-references: :class:fiftyone.module.Class``

Private Functions

# Public API delegates to private helper
def build_for(cls, path_or_url, mime_type=None):
    """Builds a Metadata object for the given file."""
    if path_or_url.startswith("http"):
        return cls._build_for_url(path_or_url, mime_type=mime_type)
    return cls._build_for_local(path_or_url, mime_type=mime_type)

# Private: underscore prefix, focused purpose
def _build_for_local(cls, filepath, mime_type=None):
    """Internal helper for local files."""
    size_bytes = os.path.getsize(filepath)
    if mime_type is None:
        mime_type = etau.guess_mime_type(filepath)
    return cls(size_bytes=size_bytes, mime_type=mime_type)

Lazy Imports

Use fou.lazy_import() for optional/heavy dependencies:

# Basic lazy import
o3d = fou.lazy_import("open3d", callback=lambda: fou.ensure_package("open3d"))

# With ensure_import for pycocotools
mask_utils = fou.lazy_import(
    "pycocotools.mask", callback=lambda: fou.ensure_import("pycocotools")
)

# Internal module lazy import
fop = fou.lazy_import("fiftyone.core.plots.plotly")

When to use:

Heavy packages (open3d, tensorflow, torch)
Optional dependencies (pycocotools)
Circular import prevention

Guard Patterns

Use hasattr() for conditional behavior:

# Check for optional attribute
if hasattr(label, "confidence"):
    if label.confidence is None or label.confidence < threshold:
        label = label.__class__()

# Check for config attribute
if hasattr(eval_info.config, "iscrowd"):
    crowd_attr = eval_info.config.iscrowd
else:
    crowd_attr = None

# Dynamic state initialization
if not hasattr(pb, "_next_idx"):
    pb._next_idx = 0
    pb._next_iters = []

Error Handling

Use logger.warning() for non-fatal errors:

# Non-fatal: warn and continue
try:
    for target in fo.config.logging_debug_targets.split(","):
        if logger_name := target.strip():
            loggers.append(logging.getLogger(logger_name))
except Exception as e:
    logger.warning(
        "Failed to parse logging debug targets '%s': %s",
        fo.config.logging_debug_targets,
        e,
    )

# Missing optional import
try:
    import resource
except ImportError as e:
    if warn_on_failure:
        logger.warning(e)
    return

# Graceful fallback
try:
    mask = etai.render_instance_image(dobj.mask, dobj.bounding_box, frame_size)
except:
    width, height = frame_size
    mask = np.zeros((height, width), dtype=bool)

Avoid Redundant Implementations

Before writing new functions, check if FiftyOne already provides the functionality.

Common Utilities in `fiftyone.core.utils` (fou)

| Function | Purpose | |----------|---------| | fou.lazy_import() | Lazy module loading | | fou.ensure_package() | Install missing package | | fou.ensure_import() | Verify import available | | fou.extract_kwargs_for_class() | Split kwargs for class | | fou.load_xml_as_dict() | Parse XML to dict | | fou.get_default_executor() | Get thread pool executor |

Common Utilities in `eta.core.utils` (etau)

| Function | Purpose | |----------|---------| | etau.guess_mime_type() | Detect file MIME type | | etau.is_str() | Check if string | | etau.ensure_dir() | Create directory if missing | | etau.ensure_basedir() | Create parent directory | | etau.make_temp_dir() | Create temp directory |

Before Writing New Code

Search existing modules for similar functionality:

grep -r "def your_function_name" fiftyone/
grep -r "similar_keyword" fiftyone/core/utils.py

Check these modules first:
- fiftyone.core.utils - General utilities
- fiftyone.core.storage - File/cloud operations
- fiftyone.utils.* - Format-specific utilities
- eta.core.utils - Low-level helpers
Red flags for redundancy:
- File path manipulation → check os.path or etau
- JSON/dict operations → check eta.core.serial
- Image operations → check fiftyone.utils.image
- Type checking → check etau.is_str(), etc.

Code Validation Checklist

Before submitting code, verify:

Style Compliance

[ ] Module has copyright header docstring
[ ] Imports in 4 groups (stdlib → third-party → eta → fiftyone)
[ ] Imports alphabetized within groups
[ ] FiftyOne imports use standard aliases (fol, fou, etc.)
[ ] Logger defined as logger = logging.getLogger(__name__)
[ ] Google-style docstrings with Args/Returns/Raises
[ ] Private functions prefixed with _

Code Quality

[ ] No redundant implementations (checked existing utils)
[ ] Heavy imports use fou.lazy_import()
[ ] Optional attributes use hasattr() guards
[ ] Non-fatal errors use logger.warning()
[ ] No bare except: (specify exception type when possible)

Testing

# Run linting
pylint fiftyone/your_module.py

# Check style
black --check fiftyone/your_module.py

# Run tests
pytest tests/unittests/your_test.py -v

Quick Reference

| Pattern | Convention | |---------|------------| | Module structure | Docstring → imports → logger → public → private → classes | | Private functions | _prefix, module-level, small & focused | | Docstrings | Google-style with Args/Returns/Raises | | Error handling | try/except + logger.warning() for non-fatal | | Lazy imports | fou.lazy_import() for optional deps | | Guard patterns | hasattr() checks for conditional behavior | | Import aliases | fol, fof, fom, fos, fou | | Constants | UPPERCASE, private: _UPPERCASE | | Class inheritance | Explicit class Foo(object): | | Redundancy check | Search fou, etau, existing modules first |