Python Import As: Consistent Namespaced Imports

Overview

This project advocates for consistent, community-wide adoption of standardized import aliases in Python, similar to the ubiquitous import pandas as pd and import numpy as np.

The Problem

Python developers have widely adopted certain conventional import aliases:

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

These conventions improve code readability and consistency across the Python ecosystem. However, for many other standard library and third-party modules, there is no established convention, leading to inconsistent practices:

# Inconsistent approaches seen in different codebases
import pathlib
from pathlib import Path
import pathlib as pl

import itertools
import itertools as it
from itertools import *

The Solution: Standardized Import Aliases

By establishing and consistently using conventional aliases for commonly-used modules, we can improve code readability, reduce cognitive load, and make Python code more uniform across projects.

Proposed Conventions

Standard Library

import argparse as ap
import collections as cl
import datetime as dt
import functools as ft
import itertools as it
import multiprocessing as mp
import pathlib as pl
import subprocess as sp
import typing as tp

Third-Party Libraries

import fastapi as fa
import numpy as np
import pandas as pd
import pydantic as pdt
import matplotlib.pyplot as plt
import seaborn as sns
import tensorflow as tf
import torch as th
import sklearn as sk
import sklearn.compose as sk_compose
import sklearn.ensemble as sk_ensemble
import sklearn.metrics as sk_metrics
import sklearn.model_selection as sk_model_selection
import sklearn.pipeline as sk_pipeline
import sklearn.tree as sk_tree
import sqlalchemy as sa

https://github.com/search?q=%22import+fastapi+as+fa%22&type=code

Benefits

1. Consistency Across Codebases

When everyone uses the same aliases, switching between projects becomes easier:

# With consistent conventions
import pathlib as pl
import itertools as it

path = pl.Path("/tmp/file.txt")
combinations = list(it.combinations([1, 2, 3], 2))

2. Reduced Verbosity

Shorter aliases reduce line length while maintaining clarity:

# Before
for item in itertools.chain(list1, list2):
    pathlib.Path(item).mkdir(parents=True)

# After
for item in it.chain(list1, list2):
    pl.Path(item).mkdir(parents=True)

3. Namespace Clarity

Explicit prefixes make it clear where functions come from:

import pathlib as pl
import datetime as dt

file_path = pl.Path("data.csv")
timestamp = dt.datetime.now()

Considerations

When to Use Aliases

Use aliases when:

• The module name is frequently used throughout the code
• The module name is long or repetitive
• You want to establish a consistent convention across your team/organization

Avoid showing toplevel modules:

Please avoid at all times imports that shadow their own toplevel module:

• from datetime import datetime
• from tqdlm import tqdm

Skip aliases when:

• The module is used only once or twice
• The full name is already very short (e.g., os, sys, re)

Examples

Example: Data Processing

import itertools as it
import collections as cl
import functools as ft

def count_combinations(items: list, size: int) -> dict:
    """Count all combinations of given size."""
    combos = it.combinations(items, size)
    counter = cl.Counter(combos)
    return dict(counter)

Contributing

Have suggestions for standard aliases? Want to propose alternatives? Contributions and discussions are welcome!

References

• PEP 8 - Style Guide for Python Code
• NumPy Documentation - Established import numpy as np convention
• Pandas Documentation - Established import pandas as pd convention

License

See license.md for details.