Sibling package imports

python

best-practices

import-protocols

project-structure

byAnton Shumikhin·Mar 6, 2025

Use relative imports with leading dots to import from sibling packages, given your folder structure supports it:

# In sibling_package/subpackage2/module2.py
# Knock knock.. who's there? It's your sibling "module1"!
from ..subpackage1 import module1

Or adjust sys.path before importing to include the parent directory:

import sys
from pathlib import Path
# Excuse me, sys.path, could you be a dear and add parent directory to our path party?
sys.path.append(str(Path(__file__).resolve().parent.parent))
from subpackage1 import module1

Remember not to run your script as __main__—it's a party pooper for relative imports.

Structuring your project: Setup script and package layout

Good structure is the key. Follow these practices:

Create setup.py: Use setuptools.setup() to define your package structure—It's like a fancy VIP invitation for packages to join your project.

# In setup.py
# Ain't no party like a setuptools.setup() party!
from setuptools import setup, find_packages
setup(name='your_package', version='1.0', packages=find_packages())

Organize as a folder with setup.py: Each package is a room at your party, an __init__.py file tells Python it's a room worth visiting.
Install in editable state: Use pip install -e <myproject_folder>—like putting your project on the VIP list to update without invites (re-installing).
Use virtual environments: They're like separate party venues for your projects venv, ensuring no party (project) crashers (conflicts).

Running scripts without headaches

How to avoid "Address not found" errors for your scripts' import statements:

Run scripts with python -m, treating directories as packages.

# On terminal
# DJ Python, drop the "-m" beat!
python -m script.py

Use pytest for testing—It's like a bouncer, managing who's on your sys.path, no need for hacks.
Have a setup.cfg as your project's guest list—It keeps metadata, making package installation smoother for others.

Import protocols: Making correct references

Here's the etiquette for importing within your package:

Prefer relative imports: They make your package a close-knit party crowd, easier to follow who's with who.
Use PEP guidance for better compatibility across Python versions.
Avoid sys.path.insert hacks: They're party crashers, causing maintainability issues.

Handling imports in large projects

The import party can spiral if not well managed. Below are best practices:

Simplify project structure: Too many rooms at your party? Redesign it!
Place tests within packages: They're the party characters everyone wants to know—they should be easy to find.
Remove unnecessary __init__.py files: Python 3.3+ are cool guests who recognize when a party (implicit namespace package) is going on without an explicit invite (__init__.py file).