Groups and Hierarchical Organization

class Group(Mapping):
    def __init__(self, parent: Group, name: str):
        """
        Create or access a group within a netCDF4 file.
        
        Args:
            parent (Group): Parent group (File for root level)
            name (str): Name of the group
        """
        ...

    def create_group(self, name: str) -> Group:
        """
        Create a new child group.
        
        Args:
            name (str): Name for the new group
            
        Returns:
            Group: The newly created group
        """
        ...

@property
def name(self) -> str:
    """Full path name of the group."""
    ...

@property
def parent(self) -> Group:
    """Parent group reference (None for root File)."""
    ...

@property
def groups(self) -> Frozen:
    """Dictionary-like access to child groups."""
    ...

@property
def variables(self) -> Frozen:
    """Dictionary-like access to variables in this group."""
    ...

@property
def dimensions(self) -> Dimensions:
    """Dictionary-like access to dimensions in this group."""
    ...

@property
def dims(self) -> Dimensions:
    """Alias for dimensions property."""
    ...

@property
def attrs(self) -> Attributes:
    """Dictionary-like access to group attributes."""
    ...

@property
def enumtypes(self) -> Frozen:
    """Dictionary-like access to enumeration types."""
    ...

@property
def vltypes(self) -> Frozen:
    """Dictionary-like access to variable-length types."""
    ...

@property
def cmptypes(self) -> Frozen:
    """Dictionary-like access to compound types."""
    ...

def create_variable(self, name: str, dimensions: tuple = (), dtype=None, 
                   data=None, fillvalue=None, chunks=None, **kwargs) -> Variable:
    """
    Create a new variable in this group.
    
    Args:
        name (str): Variable name
        dimensions (tuple): Dimension names
        dtype: Data type specification
        data: Initial data (optional)
        fillvalue: Fill value for missing data
        chunks: Chunk sizes for each dimension
        **kwargs: Additional HDF5 dataset creation parameters
        
    Returns:
        Variable: The newly created variable
    """
    ...
    
def resize_dimension(self, dim: str, size: int) -> None:
    """
    Resize an unlimited dimension.
    
    Args:
        dim (str): Dimension name
        size (int): New size for the dimension
    """
    ...

def create_enumtype(self, datatype, datatype_name: str, enum_dict: dict) -> EnumType:
    """
    Create an enumeration type.
    
    Args:
        datatype: Base data type
        datatype_name (str): Name for the enum type
        enum_dict (dict): Mapping of names to values
        
    Returns:
        EnumType: The created enumeration type
    """
    ...
    
def create_vltype(self, datatype, datatype_name: str) -> VLType:
    """
    Create a variable-length type.
    
    Args:
        datatype: Base data type
        datatype_name (str): Name for the VL type
        
    Returns:
        VLType: The created variable-length type
    """
    ...
    
def create_cmptype(self, datatype, datatype_name: str) -> CompoundType:
    """
    Create a compound type.
    
    Args:
        datatype: NumPy structured dtype
        datatype_name (str): Name for the compound type
        
    Returns:
        CompoundType: The created compound type  
    """
    ...

def flush(self) -> None:
    """Flush pending changes to disk."""
    ...

def sync(self) -> None:
    """Alias for flush() - synchronize with disk."""
    ...

def __getitem__(self, key: str):
    """Access child groups by name."""
    ...

def __contains__(self, key: str) -> bool:
    """Check if child group exists."""
    ...

def __iter__(self):
    """Iterate over child group names."""
    ...

def __len__(self) -> int:
    """Number of child groups."""
    ...

def keys(self):
    """Child group names."""
    ...

def values(self):
    """Child group objects."""
    ...

def items(self):
    """(name, group) pairs."""
    ...
    
def __repr__(self) -> str:
    """String representation of the group."""
    ...

import h5netcdf

with h5netcdf.File('hierarchical.nc', 'w') as f:
    # Create top-level groups
    obs_group = f.create_group('observations')
    model_group = f.create_group('model')
    
    # Create nested groups
    temp_obs = obs_group.create_group('temperature')
    precip_obs = obs_group.create_group('precipitation')
    
    # Each group can have its own dimensions and variables
    temp_obs.dimensions['time'] = 100
    temp_obs.dimensions['station'] = 50
    
    temp_var = temp_obs.create_variable('values', ('time', 'station'), dtype='f4')
    temp_var.attrs['units'] = 'K'
    temp_var.attrs['long_name'] = 'Temperature observations'

with h5netcdf.File('hierarchical.nc', 'r') as f:
    # Access groups by name
    obs_group = f['observations']
    temp_group = obs_group['temperature']
    
    # Or use the groups property
    for name, group in f.groups.items():
        print(f"Group: {name}")
        print(f"  Variables: {list(group.variables.keys())}")
        print(f"  Dimensions: {list(group.dimensions.keys())}")
        print(f"  Child groups: {list(group.groups.keys())}")
    
    # Navigate using parent references
    parent = temp_group.parent  # Returns observations group
    root = parent.parent        # Returns root File

with h5netcdf.File('attributed.nc', 'w') as f:
    experiment = f.create_group('experiment_1')
    
    # Set group attributes
    experiment.attrs['description'] = 'Temperature sensitivity experiment'
    experiment.attrs['start_date'] = '2023-01-01'
    experiment.attrs['investigator'] = 'Dr. Smith'
    
    # Access attributes
    print(f"Description: {experiment.attrs['description']}")
    
    # List all attributes
    for attr_name in experiment.attrs:
        print(f"{attr_name}: {experiment.attrs[attr_name]}")

with h5netcdf.File('multi_level.nc', 'w') as f:
    # Create a complex hierarchy
    data = f.create_group('data')
    
    # Geographic regions
    na = data.create_group('north_america')
    eu = data.create_group('europe')
    as_ = data.create_group('asia')
    
    # Observation types within each region
    for region in [na, eu, as_]:
        surface = region.create_group('surface')
        atmosphere = region.create_group('atmosphere')
        
        # Each can have its own coordinate system
        surface.dimensions['lat'] = 180
        surface.dimensions['lon'] = 360
        surface.dimensions['time'] = None  # Unlimited
        
        atmosphere.dimensions['lat'] = 90
        atmosphere.dimensions['lon'] = 180
        atmosphere.dimensions['level'] = 50
        atmosphere.dimensions['time'] = None  # Unlimited

with h5netcdf.File('check_contents.nc', 'r') as f:
    def explore_group(group, indent=0):
        prefix = "  " * indent
        print(f"{prefix}Group: {group.name}")
        
        if group.dimensions:
            print(f"{prefix}  Dimensions: {list(group.dimensions.keys())}")
        
        if group.variables:
            print(f"{prefix}  Variables: {list(group.variables.keys())}")
        
        if group.attrs:
            print(f"{prefix}  Attributes: {list(group.attrs.keys())}")
        
        # Recursively explore child groups
        for child_name, child_group in group.groups.items():
            explore_group(child_group, indent + 1)
    
    explore_group(f)

with h5netcdf.File('mixed.nc', 'r') as f:
    # Groups are accessed via .groups or direct indexing
    group = f['observations']  # Same as f.groups['observations']
    
    # Variables are accessed via .variables
    variable = f.variables['temperature']  # NOT f['temperature']
    
    # But within a group, both work:
    obs = f['observations']
    temp1 = obs['temperature']           # Direct access to child group
    temp2 = obs.variables['temperature']  # Access to variable (if exists)