ipld / ipld/py-ipld-dag

Legacy `Node`/`Link` classes not exported from `__init__.py`

Open
#30 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
13
Forks
9
PR merge metrics
No merged PRs in 30d

Description

The legacy `Node` and `Link` classes in `dag/dag.py` are not exported from `dag/__init__.py`, but `utils.py` references them via `node_to_link()`. This creates an inconsistency where internal code uses classes that aren't part of the public API.

### Problem

In `dag/__init__.py`:

```python
from .block import Block
from .codec import BlockCodec, BlockDecoder, BlockEncoder, ...
from .ipld_model import CID, IPLDNode, Kind, ...
from .multicodec_codes import ...

# ← Node and Link are NOT exported
```

But in `dag/utils.py`:

```python
def node_to_link(node: Any) -> Any:
from .dag import Link, Node # ← Imports from internal module

if not isinstance(node, Node):
raise TypeError("node should be an instance of type Node")

return Link("", node.size, node.multihash)
```

Users can't use `node_to_link()` without also importing from the internal `dag.dag` module.

### Proposed Solution

Either:

**Option A**: Export `Node` and `Link` from `__init__.py`:

```python
from .dag import Node, Link

__all__ = [
# ... existing exports ...
"Node",
"Link",
]
```

**Option B**: Deprecate `node_to_link()` and remove the legacy classes:

```python
import warnings

def node_to_link(node: Any) -> Any:
warnings.warn(
"node_to_link() is deprecated. Use the Block/codec API instead.",
DeprecationWarning,
stacklevel=2,
)
# ...
```

### Related

- Files: `dag/__init__.py`, `dag/dag.py`, `dag/utils.py`

Contributor guide

Open the contributing guide

Research direction

Start by reading dag/__init__.py, dag/dag.py, and dag/utils.py to understand the existing exports and node_to_link() dependency. Resolve whether the project should export Node and Link or deprecate node_to_link(); done means the chosen API direction is implemented consistently and the affected behavior is covered by the project’s tests.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 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.