# Attribute Concealment

## Purpose

The library SHALL provide mechanisms to conceal non-public attributes from
`dir()` output, reducing API noise and clearly communicating public interfaces.

## Requirements

### Requirement: Default Visibility Filtering

By default, only public attributes (not starting with `_`) MUST be visible
in `dir()` output for classes and instances using standard behaviors.

#### Scenario: Public attributes visible
- **WHEN** `dir()` is called on a class or instance with standard behaviors
- **THEN** attributes not starting with `_` MUST appear in the result

#### Scenario: Non-public attributes concealed
- **WHEN** `dir()` is called on a class or instance with standard behaviors
- **THEN** attributes starting with `_` MUST NOT appear in the result

#### Scenario: Non-public attributes still accessible
- **WHEN** a concealed attribute is accessed directly by name
- **THEN** the attribute MUST be accessible

### Requirement: Class Visibility Customization

Users MUST be able to specify which class attributes are visible via
`class_visibles`.

#### Scenario: Named visible attribute
- **WHEN** an attribute name is listed in `class_visibles`
- **THEN** that attribute MUST appear in `dir()` even if non-public

#### Scenario: Non-visible attribute
- **WHEN** an attribute name is NOT in `class_visibles`
- **THEN** concealment rules apply normally

### Requirement: Instance Visibility Customization

Users MUST be able to specify which instance attributes are visible via
`instances_visibles`.

#### Scenario: Named visible instance attribute
- **WHEN** an attribute name is listed in `instances_visibles`
- **THEN** that attribute MUST appear in `dir()` even if non-public

### Requirement: Visibility Verifiers

Visibility verifiers MUST support names, regexes, and predicates, matching
the mutability verifier interface.

#### Scenario: Regex-based visibility
- **WHEN** an attribute name matches a regex in `class_visibles` or `instances_visibles`
- **THEN** that attribute MUST appear in `dir()`

#### Scenario: Predicate-based visibility
- **WHEN** a predicate returns `True` for an attribute name
- **THEN** that attribute MUST appear in `dir()`

### Requirement: Wildcard Visibility

Users MUST be able to disable concealment entirely using a literal `'*'`.

#### Scenario: Wildcard shows all attributes
- **WHEN** `class_visibles` or `instances_visibles` is set to `'*'`
- **THEN** all attributes MUST appear in `dir()` (Python default behavior)

### Requirement: Visibility Verifier Inheritance

Visibility verifiers MUST be inherited and composable across class
hierarchies.

#### Scenario: Inherited visibility names
- **WHEN** a subclass inherits from a class with custom visibles
- **THEN** the subclass MUST inherit those visible names

#### Scenario: Composed visibility names
- **WHEN** a subclass defines additional visibles
- **THEN** both parent and child visibles MUST be active