Centralization of a shared values in common file

[LVivona]

Context

While reviewing the py-libp2p repository, I noticed a recurring pattern of duplicated configuration values and imports. Although not critical in retrospect to work-ability, this kind of redundancy introduces subtle maintenance friction: it creates drift over time and places unnecessary cognitive load on maintainers, who must remember where each constant or shared function is defined and whether it's safe to reuse or modify. Centralizing these values could reduce mental overhead and make the codebase easier to navigate and maintain.

Problem

• Duplicate values across modules (e.g., DEFAULT_TIMEOUT, CHUNK_SIZE, PROTOCOL_ID)
• Cognitive load increases when trying to trace origin or reason for a value

Proposal

Introduce a central file (e.g., common.py) to house shared configuration and semantic values.
A simple way to decide when centralization is appropriate is to treat it similarly to how we structure Python modules: if multiple submodules or directories within py-libp2p depend on the same value, it likely belongs in a shared location. This mirrors the principle of avoiding duplication across modules by promoting a single source of truth for constants, protocol identifiers, default timeouts, and other reusable values. It not only improves maintainability but also reduces ambiguity about where a value should come from.

One can visualize this central file as the intersection point in a dependency graph, imagine strings connecting each module that references a shared constant. As more strings converge on the same value, they begin to pinch into a single point. That "pinch" represents the ideal location for centralization. The tighter the convergence, the stronger the case for extracting that value into common.py.

Example:

libp2p/kad_dht/common.py

"""
Shared constants and protocol parameters for the Kademlia DHT.
"""

from libp2p.custom_types import (
    TProtocol,
)

# Constants for the Kademlia algorithm
ALPHA = 3  # Concurrency parameter
PROTOCOL_ID = TProtocol("/ipfs/kad/1.0.0")
QUERY_TIMEOUT = 10

TTL = DEFAULT_TTL = 24 * 60 * 60  # 24 hours in seconds

example of the usage becomes common in module kad_dht:

libp2p/kad_dht/kad_dht.py

from .common import (
    ALPHA,
    PROTOCOL_ID,
    QUERY_TIMEOUT,
)

libp2p/kad_dht/peer_routing.py

from .common import (
    ALPHA,
    PROTOCOL_ID,
)

libp2p/kad_dht/provider_store.py

from .common import (
    ALPHA,
    PROTOCOL_ID,
    QUERY_TIMEOUT,
)

libp2p/kad_dht/routing_table.py

from .common import (
    PROTOCOL_ID,
)

libp2p/kad_dht/value_store.py

from .common import (
    DEFAULT_TTL,
    PROTOCOL_ID,
)

---

Benefits

• Simplifies imports: Easier to find and trace shared values
• Improves consistency: Single source of truth for values used across modules
• Easier refactoring: Updating values in one place
• Supports autocompletion and discoverability

Considerations

• Over-centralization may lead to a "all in one file" if not scoped carefully. it is not meant to replace other file specifics such as typing.py or utils.py
• Avoid leaking context-specific values into shared scope (keep module-specific values local)

---

📎 Related Issues

• chore(kad_dht): centralize shared values in common.py file #695

[seetadev]

@LVivona : Thank you so much for taking the time to open this discussion page and articulate your observations so clearly. You’ve captured a subtle but important challenge that many growing codebases face—namely, the creeping friction caused by duplicated configuration values and scattered constants.

Your framing of the problem—particularly the metaphor of shared values “pinching” into a central convergence point—is both elegant and insightful. It really helps visualize why centralizing configuration is not just a matter of convenience, but a meaningful step toward lowering cognitive overhead and improving maintainability.

The proposed solution makes a lot of sense. Establishing a common.py (or similarly structured central module) for shared constants, timeouts, and protocol identifiers will definitely help avoid ambiguity, reduce drift, and allow contributors to focus more on core functionality instead of tracing the origin of values.

This kind of thoughtful design thinking is incredibly valuable to the future health of py-libp2p. I’m really grateful you surfaced this and offered a clear path forward. Looking forward to your PR :)