apache / apache/iceberg-python

Explicitly declare supported public APIs with '__all__'

Open
#1,099 4 comments 6 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
1.1k
Forks
581
Avg merge
1d 17h
Merged PRs (30d)
78

Description

### Feature Request / Improvement

Currently, we rely on the informal naming conventions (with or without underscore) to distinguish between a public or private API.

It will be helpful to declare the names of public APIs in the `__all__` attribute on all our public API supporting modules as it will:
- control what APIs we expose to wildcard imports
- enhance discoverability of public APIs (when reading the source code as users or developers)
- and allow tools like [Griffe](https://mkdocstrings.github.io/griffe/guide/users/navigating/#object-visibility) to detect the correct public APIs for backwards compatibility analysis in our CI

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by identifying the modules that support the public API and reviewing their current naming conventions. Add __all__ declarations for the intended public names, then verify wildcard imports and confirm that Griffe detects the same API surface for compatibility analysis.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, developer-experience
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.